Container and Signature Service

1. Service Overview

container-signature-service is the DMSS service responsible for container lifecycle, electronic signatures, e-sealing, timestamping, and PDF signing operations.

It is an orchestration service: it does not act as a long-term archive itself. Instead, it reads/writes documents through dmss-archive-services and coordinates multiple signing providers.

2. Scope and Responsibilities

Primary responsibilities:

• Create, compose, enrich, and inspect ASiC-E/BDoc containers.
• Sign containers/documents/PDFs with multiple methods (Smart-ID, Mobile-ID, ID-card/Web-eID, OAuth2 providers, LVRTC, Asseco, BankID, AMA, LT-ID, SMS flows).
• Execute e-sealing and token-based stamping flows.
• Perform PDF-specific operations (visual signing, merge, validation, DSS repair/extension).
• Provide encryption endpoints (CDOC style flows and certificate-based encryption endpoints).
• Persist signing session state for asynchronous and polling flows (Hazelcast-backed).

Out of scope:

• Long-term business document storage.
• Archive connector logic (handled by dmss-archive-services).

3. Architecture

Runtime building blocks:

• API layer: Spring Boot REST controllers under controllers/api and controllers/api/v2.
• Signing orchestration: SignerServiceFactory, signing service implementations per method/provider.
• Archive gateway: DmssArchiveService + helper classes call archive APIs.
• Session/cache layer: Hazelcast maps for signing sessions, locks, OTP attempts, and provider state.
• Optional persistence: JPA + Liquibase used for extended auditing (LogConsoleData) and related service data.
• Scheduling/async: enabled via @EnableScheduling and @EnableAsync.

Request flow (typical):

1. API receives signing request with document/container ID.
2. Service downloads document/container content via archive API.
3. Service initiates provider-specific signing session.
4. Intermediate session state is cached in Hazelcast.
5. Client polls session status endpoint or receives callback.
6. Signed content is written back to archive.

4. API Surface

Main endpoint groups (base paths):

Domain	Base Path	Purpose
Health	/ping, /ping/ready	Liveness/readiness checks
Container lifecycle	/api/container	Create/compose/update/download/info/signatures/repair/extend
Container compose v2	/api/v2/container/compose	Dedicated v2 compose API
Smart-ID	/api/signing/smart	Sign + session polling + cert/hash flows
Mobile-ID	/api/signing/mobile	Sign + session polling
ID-card / Web-eID	/api/signing/ic, /api/signing/webeid	Hash-generation and finalize flows
OAuth2 signing	/api/signing/oauth2	Provider-based OAuth2 sign flows
LVRTC/eParaksts	/api/signing/lvrtc, /api/signing/lvrtc-banking	LVRTC sign and status flows
Other providers	/api/signing/asseco, /api/signing/bankid, /api/signing/evrotrust, /api/signing/ama, /api/signing/ltid, /api/signing/sms	Provider-specific integrations
E-sealing / token stamping	/api/eseal, /api/stamping	Seal/stamp with token/server infrastructure
Timestamping	/api/timestamping	Add timestamp(s) to containers/documents
PDF utilities	/api/pdf, /api/signing/visual, /api/forms	PDF inspect/merge/visual sign/form fill
Encryption	/api/encrypt	Encryption + encrypted container creation
OCSP/CAdES/session ops	/api/ocsp, /api/cades, /api/session, /api/hazelcast	Crypto/session support endpoints

Notes:

• Controller layer includes OpenAPI annotations across endpoints.
• Session-oriented methods return a session token and require follow-up polling calls.

5. Configuration Model

Core runtime properties in src/main/resources/application.yml:

Category	Key Prefix	What It Controls
Service identity	server.port (default 8092)	HTTP port
Archive integration	archive-services.*	Primary/fallback archive URL and forwarded headers
Signing providers	smartId.*, mobile-id.*, lvrtc.*, zealId.*, evrotrust.*, asseco.*, ama.*, ltid.*, bankid.*	Provider credentials, endpoints, behavior
DigiDoc & trust	digidoc4j.*, validation.*	Signature container processing and validation profile
PDF behavior	pdf.*, pdfConverter.*	Visual signature defaults, watermarking, conversion
Stamping	digital-stamping-service.*, timestamp.*	Token discovery and timestamp providers
Session/cache	hazelcast.*	TTL, clustering, eviction, instance name
Async callbacks	callbackService.*, dmss-metadata-update-service.*	External callback and metadata update behavior
Offline mode	offline-mode.*	Allowed document types/signing methods for offline scenarios
Auditing	process-and-auditing-service.*	Extended auditing and event metadata
CORS	signatureServices.cors.disabled	Enables permissive CORS config when true

6. Security Model

• Service-level HTTP security is minimal by default (SecurityConfig disables CSRF and CORS filters at Spring Security layer).
• Trust boundary is typically upstream (API gateway / internal network policies / mTLS).
• Provider-level security is enforced in integration clients (keys, secrets, truststores, provider cert chains).
• Signature validation behavior is configurable (validation.*, digidoc4j.*).

Operational implication:

• Deploy this service behind authenticated ingress unless your network is already strictly controlled.

7. Data and State

State model:

• Durable business artifacts: stored in archive service, not in this service.
• Ephemeral signing state: Hazelcast maps (map, locked-containers, OTP maps).
• Optional local DB state: extended auditing records via JPA/Liquibase.

Session characteristics:

• TTL-based expiration (hazelcast.expireInminutes).
• Explicit lock/unlock around active signing sessions.
• Async completion updates session state and can trigger callback URLs.

8. Integrations

Key external dependencies:

• dmss-archive-services (mandatory for document/container persistence).
• Optional dmss-document-generation-service for generation workflows.
• Optional digital-stamping-service for token stamping / discovery.
• Optional dmss-process-and-auditing-service for enriched auditing.
• Signature providers: Smart-ID, Mobile-ID, LVRTC/eParaksts, Asseco/SimplySign, ZealID (OAuth2), Evrotrust, LT-ID, AMA, BankID.

Internal integration behavior:

• Select headers are forwarded to downstream services (archive-services.forwardHttpHeaders).
• Callback behavior supports static callback URL or archive document-type-driven callback URL.

9. Build, Run, Deploy

Technology baseline:

• Java 21
• Spring Boot
• Gradle wrapper

Container image:

• Available on Docker Hub: trustlynx/container-signature-service
• Image page: https://hub.docker.com/r/trustlynx/container-signature-service
• Image download/pull URL: docker.io/trustlynx/container-signature-service
• Pull command: docker pull trustlynx/container-signature-service

Build:

./gradlew clean build

Run (example):

java -jar build/libs/container-signature-service.jar --spring.config.location=/path/to/application.yml

Deployment notes:

• Designed for containerized deployment (Dockerfile and k8s manifests exist in repo).
• Configure provider credentials and trust material per environment.
• Ensure archive endpoint reachability before enabling signing flows.

10. Operations and Troubleshooting

Health/ops endpoints:

• /ping returns pong.
• /ping/ready returns readiness (200 or 502 after abort trigger).
• /api/hazelcast/count provides map-size visibility for session troubleshooting.
• Actuator/Prometheus metrics available via Spring Boot + Micrometer config.

Scheduled jobs:

• Token discovery scheduler: digital-stamping-service.tokensDiscoverySchedule (enabled via tokensDiscoveryEnabled=true).

Common failure points:

• Provider credential misconfiguration (timeouts/403/errors from provider APIs).
• Missing/incorrect forwarded headers for downstream integrations.
• TTL expiry in long-running signing sessions causing SESSION_NOT_FOUND behavior.
• Archive unavailability or fallback path mismatch.

11. Non-Goals and Boundary Decisions

• This service intentionally focuses on cryptographic/signing orchestration.
• Persistence durability and storage lifecycle management are delegated to archive services.
• Security hardening is expected at deployment perimeter (gateway/network), not only in service-local HTTP configuration.